/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2008-2011, Salzburg Research. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * - Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 * - Neither the name of the LMF library client Project nor the names of its contributors
 * may be used to endorse or promote products derived from this software
 * without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * Contributor(s):
 * Stephanie Stroka
 *
 * File Info:
 * User: Stephanie Stroka
 * Date: 2011/08/19
 * Time: 18:04
 *
 * Project: lmflib
 */

package kiwi.facading.api;

import kiwi.facading.model.KiWiTriple;
import kiwi.facading.model.resources.KiWiNode;
import kiwi.facading.model.resources.KiWiResource;
import kiwi.facading.model.resources.KiWiUriResource;

import java.util.Set;

/**
 * Created by IntelliJ IDEA.
 * User: sstroka
 * Date: 01.06.2011
 * Time: 13:51:47
 * To change this template use File | Settings | File Templates.
 */
public interface TripleStore {
    

    // *****************************************************************************************************
    // methods for creating and removing triples
    // *****************************************************************************************************


    /**
     * Create or retrieve a KiWi triple in this knowledge space using the provided subject, predicate, and
     * object.
     * <p>
     * If a triple with the same subject/property/object already exists in the knowledge base,
     * it is returned.
     * <p>
     * If a triple with the same subject/property/object does not yet exist, this method will automatically
     * generate a new triple id for the triple, and then store the triple in
     * the knowledge base. The rationale behind this is that many methods of ExtendedTriple directly work on
     * the knowledge base and require both, a triple id and the triple to be persisted.
     *
     * @param subject
     * @param property
     * @param object
     * @param context
     */
    public KiWiTriple createTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);




	/**
	 * Remove a triple from the repository. This method only adds the triple to the
     * current transaction data; the triple will be persisted to the database and repository
     * on transaction commit.
     *
	 * @param triple
	 */
	public void removeTriple(KiWiTriple triple);


	/**
	 * Remove a triple from the repository with the given subject, property, and object
	 * @param subject
	 * @param property
	 * @param object
	 */
	public void removeTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);

	/**
	 * List all triples for a given subject resource
	 * @return a set of triples
	 */
	public Set<KiWiTriple> listTriples(KiWiResource subject);

    /**
	 * List all triples for a given subject resource and context
	 * @return a set of triples
	 */
	public Set<KiWiTriple> listTriples(KiWiResource subject, KiWiResource context);

    /**
	 * List all triples for a given subject, property and object resource and context
	 * @return a set of triples
	 */
    public Set<KiWiTriple> listTriples(KiWiResource subject, KiWiUriResource property, KiWiResource context);

    /**
	 * List all triples for a given subject and property resource and context
	 * @return a set of triples
	 */
    public Set<KiWiTriple> listTriples(KiWiResource subject,
                                       KiWiUriResource property, KiWiNode object, KiWiResource context);

    /**
     * Check whether the triple formed by the parameters exists.
     * @param subject
     * @param property
     * @param object
     * @return
     */
    public boolean hasTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object);

    public boolean hasTriple(KiWiResource subject, KiWiUriResource property, KiWiNode object, KiWiUriResource context);

	public void clearCaches();

}
